Alias

SignerProcessCreation

Description

Creates a document signature process. This process can be used for the following:

To perform the signing of a document that is included in the request. This document can be a PDF document (PAdES-Basic, PAdES-BES, and PAdES-EPES signatures) or a document of any other type (XMLDSig, XAdES-BES, and XAdES-EPES).
To obtain a single signature of several external data objects from their hashes or of multiple XMLDSig/XAdES Manifest objects. This signature can only be an externally detached XMLDSIg/XAdES signature.
To perform a batch of signatures on a set of Document and signature definitions resources. These resources must have been created previously. Each batch signature can be a document's signature, the signature of several external data objects (obtained from their hashes), or the signature of several XMLDSig/XAdES Manifest objects. When a document is signed, it can be a PDF document (PAdES-Basic, PAdES-BES, and PAdES-EPES signatures) or a document of any other type (XMLDSig, XAdES-BES, and XAdES-EPES). When several external data objects (from their hashes) or multiple XMLDSig/XAdES Manifest objects are signed, this signature can only be an externally detached XMLDSIg/XAdES signature.

In the first and second cases, the operation also creates the Document and signature definitions resource corresponding to the signature process created.

If this process is successfully executed, the corresponding signed documents or signatures must be obtained via the obtain a document operation.

Request

POST /trustedx-resources/esignsp/v2/signer_processes

Authorization

The request must contain a bearer access token generated by an authorization server of the platform. This token must have a scope that includes the urn:safelayer:eidas:sign:process:document value and must be used as explained in RFC 6750. Basically, the access token must be included in an Authorization header as follows:

Authorization: Bearer <token>

The access token can be obtained via an authorization code grant or client credentials grant OAuth 2.0 flow.

Content-Type Header

There are the following possibilities, depending on whether the operation is executed for signing a document provided or whether it is executed for signing multiple external data objects from their hashes.

If the operation is executed to sign a document in the request:

Content-Type: multipart/form-data; boundary=<part_boundary_mark>

Where <part_boundary_mark> is the string that delimits the parts of the multipart entity inserted in the body.

If the operation is executed to obtain the signature of multiple external data objects from their hashes or multiple XMLDSig/XAdES Manifest objects:

Content-Type: application/json

If the operation is executed to perform a batch of signatures:

Content-Type: application/json

Body

There are three possibilities, depending on whether the operation is executed for signing a document provided, generating a signature on several external objects from hashes provided or signing documents that contain (or are referred to by their hashes) a group of document and signature definitions resources created previously.

The operation is executed to sign a document in the request
The operation is executed to obtain the signature of multiple external data objects from their hashes or multiple XMLDSig/XAdES Manifest objects
The operation is executed to perform a batch of signatures

The operation is executed to sign a document in the request

In this case, the body contains a multipart/form-data entity with two parts: one ("process") containing a JSON object with the data required for creating the signature process; the other ("document“), the document to be signed: The Content-Type header of this part specifies the type of this document (a PDF if the value in the header is application/PDF, an XML document if the value is text/xml;charset="UTF-8", etc.). The Content-Transfer-Encoding header of the "document" part is only necessary when the document to be signed is encoded in binary (a PDF document, a PNG image, etc).

------x1Xxx2XXxxx3XXX3xxxXX2xxX1x
Content-Disposition: form-data; name="process"
Content-Type: application/json
 
{
    "process_type" : {string},
    "signer" : {SignatureDefinition},
    "labels" : [ [{string}] ],
    "ui_locales" : [{string}],
    "finish_callback_url" : {string},
    "views" : {
        "document_agreement" : {
            "skip_server_id" : {boolean},
            "document_info" : {
                "html_body_content" : {string}
            }
        }
    },
    "timestamp" : {
        "provider_id" : {string}
    }
    "identity_validation" : {
        "provider_id" : {string}
    }
}
------x1Xxx2XXxxx3XXX3xxxXX2xxX1x
Content-Disposition: form-data; name="document"; 
Content-Type: application/pdf
Content-Transfer-Encoding: binary
 
<doc>
------x1Xxx2XXxxx3XXX3xxxXX2xxX1x--

The operation is executed to obtain the signature of multiple external data objects from their hashes or multiple XMLDSig/XAdES Manifest objects

In this case, the body contains a JSON object with the data required for creating the signature process:

 {
    "process_type" : {string},
    "signer" : {SignatureDefinition},
    "labels" : [ [{string}] ],
    "ui_locales" : [{string}],
    "finish_callback_url" : {string},
    "views" : {
        "document_agreement" : {
            "skip_server_id" : {boolean},
            "document_info" : {
                "html_body_content" : {string}
            }
        }
    },
    "timestamp" : {
        "provider_id" : {string}
    }
    "identity_validation" : {
        "provider_id" : {string}
    }
}

The operation is executed to perform a batch of signatures

In this case, the body contains a JSON object with the data required for creating the signature process; The documents[] property is required and the signer property is optional.

 {
    "process_type" : {string},
    "signer" : {SignatureDefinition},
    "labels" : [ [{string}] ],
    "documents" : [{ "id" : {string} }],
    "ui_locales" : [{string}],
    "finish_callback_url" : {string},
    "views" : {
        "document_agreement" : {
            "skip_server_id" : {boolean},
            "document_info" : {
                "html_body_content" : {string}
            }
        }
    },
    "timestamp" : {
        "provider_id" : {string}
    }
    "identity_validation" : {
        "provider_id" : {string}
    }
}

Properties of the JSON object containing the data for creating the signature process

The JSON object containing the data used for creating the signature process has the following properties:

Property	Use	Description
`process_type`	Required	Signature process type. This property supports two values: `"urn:safelayer:eidas:processes:document:sign:esigp":` The process uses a signature identity managed by the TRIDENT platform. At the start of the process, the user is authenticated and prompted for authorization for their signature identities to be queried. `"urn:safelayer:eidas:processes:document:sign":` The process uses a signature identity managed by the TRIDENT or an external application. At the start of the process, the user is not authenticated or prompted for authorization for their signature identities to be queried. Instead, both tasks are performed later if the user selects an eSigP signing identity schema.
`signer`	Optional	Definition of the signature to be performed. This property is represented in JSON as a signature definition resource. In the specific case of this operation, the representation of the resource can only have the `signature_policy_id` and `parameters attributes`. It can only be omitted if the JSON object contains the `documents[]` property and each document and signature definitions resource to which this property points to contains the definition of the corresponding signature Important If the request contains the document to be signed and the signature definition lacks some or all of the parameters (of the `parameters` property or one of its subordinate optional properties), the signature will be performed as explained in Behaviour for When Parameters Are Missing from the Signature Definition of the obtain the hash of the document in accordance with a signature definition operation.
`labels[]`	Optional	List of filters to be applied on the set of signing identities of the user for selecting the identity to be used in the signature process. Each filter is defined as a list of labels. When the filter is applied, the user's signing identities that contain all the specified labels are selected. This is how the TRIDENT selects the signing identities of the user that contain the labels of one of the filters. For example, if the list of filters is `[["label1", "label2"], ["label3", "label4"]]`, TRIDENT selects all the user's signing identities that have the `label1` and `label2` labels and also all those that have the `label3` and `label4` labels. Where TRIDENT selects more than one signing identity, the user is prompted to select which one they want to use. If the TRIDENT does not select any signing identity, the signature process ends with an error. This property is optional. If omitted, the TRIDENT does not apply any filter to the selection of the user's signing identities. Important Currently only lists with one filter are supported (i.e., the second and following filters are not taken into account). Thus, the user's signing identities that contain the labels specified in the first filter of the list (which we recommend is, for the sake of clarity, the only filter) are selected
`documents[]`	Optional	List of the Document and signature definitions resources that must be used to perform the batch of signatures. Each list element is an object with only the `"id"` property and whose value is the identifier of one of those resources previously created with the Create a document and signature definitions resource.
`ui_locales[]`	Optional	List of preferred languages for the texts of the pages sent to the user's browser during the signature process. Each language is specified with a RFC 5646 label. TRIDENT uses the first language that it can provide. This property is optional. If omitted, the TRIDENT uses the list of languages specified by the browser in the `Accept-Language` header of the request message.
`finish_callback_url`	Required	Callback URL. The client application waits to be notified of the finalization of the signature process at this URL. TRIDENT adds the `status` parameter to the query string of this URL to specify the status of the process when it finishes (`finished`, `failed` or `canceled`): `finished`: The process finished successfully. `failed`: The process did not finish successfully because an error occurred. `canceled`: The process did not finish successfully because it was cancelled.
`views`	Optional	Information on the pages to be sent to the user's browser during the signature process. This property is optional. If omitted, there are two possibilities: If the process is for signing a document, TRIDENT sends to the browser a default page for acknowledging having read the document. If the process is for signing multiple external data objects from their hashes, TRIDENT cannot send anything to the browser
`views.document_agreement`	Required	Information on the page via which the user will agree the document or data on which the signature process will be performed. Note This property is required only if the `views` property is present.
`views.document_agreement.skip_server_id`	Optional	Indication on whether the document agreement page can be omitted where the document signature is generated on the server. This property is optional and its default value is `false`.
`views.document_agreement.document_info`	Required	Information on the document on which the signature process is performed that must be included in the document agreement page. Note This property is required only if the `views` property is present.
`views.document_agreement.document_info.html_body_content`	Required	base64 encoding of the HTML document’s body that contains information on the document on which the signature process is performed that must be displayed in the document agreement page. The delimiting tags of this body must be excluded from the base64 encoding (i.e., the `<body>` and `</body>` tags). Note This property is required only if the `views` property is present.
`timestamp`	Optional	If present, indicates that the signature must have a time-stamp. If it is not present, it must not have one.
`timestamp.provider_id`	Optional	If present, indicates the system's time-stamp policy that must be used for obtaining the time-stamp for the signature. If not present, the platform selects the policy.
`identity_validation`	Optional	If present, the signing identity must be validated before signing.
`identity_validation.provider_id`	Optional	If present, it indicates the system's certificate validation policy for validating the signing identity. If not present, the platform selects the policy.

Response

Status-Line

If the document signature process is created successfully, the HTTP response will contain the following Status-Line (see HTTP Response Status for all the possible cases).

HTTP/1.1 201 Created

Location Header

URL of the document signature process created. This URL has the following structure:

Location: https://<host>:<port>/trustedx-resources/esignsp/v2/signer_processes/{signature_process_id}

Where {signature_process_id} contains the identifier of the document signature process created.

Content-Type Header

Content-Type: application/json

Body

JSON representation of the document signature process created.

Example

HTTP/1.1 201 Created
Location: http://www.example.com/trustedx-resources/esignsp/v2/signer_processes/idp_111
Content-Type: application/json
 
{
    "id" : "idp_111",
    "self" : "http://www.example.com/trustedx-resources/esignsp/v2/signer_processes/idp_111",
    "process_type" : "urn:safelayer:eidas:processes:document:sign:esigp",
    "tasks" : {
        "pending" : [
            {
                "type" : "UserBrowserTask",
                "id" : "idt_222",
                "url" : "http://www.example.com/trustedx-resources/esignsp/v2/ui?signerProcessId=idp_111"
            }
        ]
    },
    "documents" : [ 
        {
            "url" : "http://www.example.com/trustedx-resources/esignsp/v2/documents/idd_333"
        }
    ]
}